Python API Reference

This page documents the Python classes, interfaces, methods, and functions in void_builder.

Module: void_builder.core.config_loader

Class Config(data)

Data wrapper for configuration dictionaries with dot-notation access.

Methods

  • get(path: str, default: Any = None) -> Any: Retrieves configuration value using dot notation (e.g., system.iso_label).

  • to_dict() -> Dict[str, Any]: Returns raw dictionary underlying data.

Class ConfigAssembler(config_root)

Composition brain that merges global manifests and component profiles.

Parameters

  • config_root (str or Path): Directory containing configuration subfolders.

Methods

  • assemble_options(target_arch: str, request: ConfigAssemblyOptions) -> Config: Assembles profiles and overrides from a typed request. ConfigAssemblyOptions groups profile selections in PresetOptions and identity, user, and boot settings in CustomizationOverrides.

  • assemble(target_arch: str, *args, **kwargs) -> Config: Backward-compatible adapter for the former positional and named options. New integrations should use assemble_options and ConfigAssemblyOptions.

  • validate(target_arch: str, *args, **kwargs) -> Dict[str, Any]: Validates component profile existence and returns structured audit report {"valid": bool, "errors": list, "summary": dict}.

Module: void_builder.core.orchestrator

Class BuildOrchestrator(...)

High-level build controller coordinating configuration assembly, toolchain setup, chroot creation, and image generation.

Methods

  • validate() -> Dict[str, Any]: Runs configuration validation without executing build pipeline.

  • run_build(output_iso: str, output_format: str = "iso") -> Path: Executes the complete build workflow and returns output file path.

Module: void_builder.core.iso_engine

Class ISOEngine

Abstract base class and registry for architecture build engines.

Registered Engines

  • @ISOEngine.register("x86_64") / @ISOEngine.register("i686") / @ISOEngine.register("aarch64"): VoidEngine

  • @ISOEngine.register("rpi-aarch64") / @ISOEngine.register("pinebookpro") / @ISOEngine.register("asahi"): PlatformEngine

Class BaseEngine(arch, config, toolchain)

Abstract engine providing core utility functions.

Methods

  • setup_workdir(workdir: Optional[Union[str, Path]] = None) -> Path: Resolves writable workspace directory.

  • _generate_manifest_and_checksums(output_file_path: str) -> None: Calculates SHA256/SHA512/MD5 hashes, writes manifest.json, and creates an ephemeral per-build GPG signature and exported public key.

  • export_tarball(output_path: str) -> str: Compresses rootfs into .tar.xz archive.

Class VoidEngine

Engine handling standard PC ISO 9660 hybrid image creation.

Methods

  • setup_chroot(workdir: str) -> None: Prepares airootfs and iso-staging directories.

  • install_packages() -> None: Invokes ChrootManager to install target packages.

  • post_install_configure() -> None: Applies locale, user, service, and Plymouth customizations.

  • build_bootloaders(mountpoint: str) -> None: Assembles SYSLINUX and GRUB EFI boot files.

  • finalize_isofile(output_path: str) -> None: Runs mksquashfs and xorriso to create final .iso.

Class PlatformEngine

Engine handling platform-specific boot asset staging and root-filesystem configuration.

Methods

  • finalize_isofile(output_path: str, output_format: str = "iso") -> Optional[str]: Builds ISO output. Disk image output is coordinated separately by ISOBuilder and DiskEngine.

Module: void_builder.core.disk_engine

Class DiskEngine(request: DiskEngineRequest)

Builds partitioned disk images for supported target architectures.

Methods

  • build_disk_image(target_format: str = "img") -> Path: Creates the disk image, optionally converts it to a supported raw or VM format, and applies configured compression.

Module: void_builder.core.chroot_manager

Class ChrootManager(chroot_path, toolchain, mode, arch, config)

Manages virtual filesystem mounting (/proc, /sys, /dev), xbps-install commands, and user/service setup inside target chroot.

Methods

  • mount() -> None: Mounts pseudo-filesystems.

  • umount() -> None: Safely unmounts pseudo-filesystems.

  • install_packages(package_plan: Dict[str, List[str]], repos: Optional[List[str]] = None, reinstall: bool = True) -> None: Installs the requested package groups into the chroot.

  • run_command(command: Union[str, List[str]], env: Optional[Dict[str, str]] = None, check: bool = True, input_text: Optional[str] = None) -> str: Runs a shell command string or argument vector in the chroot and returns standard output.

  • run_reconfigure() -> None: Executes Void 3-pass xbps-reconfigure -a.

Module: void_builder.core.stage_manager

Class StageManager

Resolves, verifies, extracts, and creates reusable Void Linux stage archives.

Methods

  • resolve_tarball(tarball_arg: str) -> Path: Resolves a local path, file:// URI, HTTPS URL, or automatic cache candidate. Plain HTTP URLs are rejected.

  • verify_tarball(tarball_path: Path) -> str: Verifies the archive against an explicit SHA-256 or an adjacent .sha256 sidecar.

  • extract_tarball(tarball_path: Path, target_root: Path) -> None: Extracts the verified archive; real-mode extraction requires root privileges.

  • create_stage_tarball(source_root: Path, output_tarball: Path, compression: str = "xz") -> Path: Creates a compressed stage archive from a root filesystem.

Module: void_builder.core.customizer

Class SystemConfigurator(chroot_manager)

Applies low-level Linux system customizations inside target rootfs.

Methods

  • load_from_config(config: Config) -> None: Loads hostname, locale, timezone, users, services, Plymouth, and Dracut configurations.

  • apply() -> None: Executes customization steps sequentially.